# Wi-Fi/BT

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

The **Quectel Pi** Debian development board supports **Wi-Fi** and **Bluetooth (BT)** connections. This document is based on the current board-side environment: the system is Debian GNU/Linux 13 (trixie), the wireless network interface is `wlan0`, the NetworkManager service is active, and commands such as `nmcli`, `wpa_cli`, `wpa_supplicant`, and `bluetoothctl` are available on the board.

> 💡 It is recommended to connect to Wi-Fi through the Debian desktop or `nmcli` first. Use `wpa_cli` / `wpa_supplicant` only when NetworkManager is unavailable, low-level debugging is required, or wpa_supplicant behavior needs to be verified.

# Wi-Fi Usage

## Method 1: Connect to Wi-Fi from the Debian Desktop

If a MIPI/HDMI display is connected and the board has entered the Debian GNOME desktop, you can connect to a wireless network directly from the desktop network menu. This method is suitable for basic functional verification and does not require manual command input.

1. Connect the display, mouse, and keyboard. Power on the development board and enter the Debian desktop.

2. Click the system status area in the upper-right corner of the desktop to expand the network menu.

3. Make sure the Wi-Fi switch is turned on. If it is off, enable Wi-Fi first.

4. Select the target SSID from the wireless network list.

5. Enter the Wi-Fi password and confirm the connection.

6. After the connection succeeds, verify network connectivity by opening a webpage in the browser, or by running `ip addr show wlan0` and `ping -c 4 8.8.8.8` in the terminal.

## Method 2: Connect to Wi-Fi with nmcli (Recommended Command-Line Method)

`nmcli` is the command-line tool for NetworkManager. In the current Debian board environment, NetworkManager is running and `wlan0` is recognized as a Wi-Fi device. Therefore, this method is recommended for command-line Wi-Fi connection.

**1. Check wireless device status**

```bash
nmcli general status
nmcli radio wifi
nmcli device status
```

Normally, `wlan0` should be shown as a `wifi` device. If Wi-Fi is shown as disabled, run:

```bash
nmcli radio wifi on
```

**2. Scan nearby Wi-Fi networks**

```bash
nmcli device wifi rescan ifname wlan0
nmcli device wifi list ifname wlan0
```

**3. Connect to the target Wi-Fi**

```bash
nmcli device wifi connect "SSID_NAME" password "Wi-Fi_PASSWORD" ifname wlan0
```

If the SSID or password contains spaces or special characters, keep the double quotation marks. After the connection succeeds, NetworkManager automatically saves the connection profile. In most cases, the board will reconnect automatically after reboot or network recovery.

**4. Check the connection result**

```bash
nmcli connection show --active
ip addr show wlan0
ip route
ping -c 4 8.8.8.8
```

**5. Common maintenance commands**

```bash
# Disconnect the current wlan0 connection
nmcli device disconnect wlan0

# Bring up a saved connection again
nmcli connection up "SSID_NAME"

# Delete a saved connection
nmcli connection delete "SSID_NAME"
```

## Method 3: Connect to Wi-Fi with wpa_cli / wpa_supplicant (Low-Level Debugging Method)

`wpa_supplicant` is the low-level Linux component responsible for Wi-Fi authentication and connection, and `wpa_cli` is its interactive control tool. This method is suitable when NetworkManager is not managing the interface, or when driver, firmware, or authentication behavior needs to be verified. If `wlan0` is currently managed by NetworkManager, disconnect it or stop NetworkManager first to avoid two processes controlling the same wireless interface at the same time.

> 💡 Before using the wpa_supplicant method, make sure it will not interrupt the current remote connection. If the development board depends on Wi-Fi for remote login, stopping NetworkManager may disconnect the network.

**1. Stop NetworkManager from managing wlan0 (run only when needed)**

```bash
nmcli device disconnect wlan0
# Or temporarily stop NetworkManager during debugging
systemctl stop NetworkManager
```

**2. Create the wpa_supplicant configuration file**

```bash
wpa_passphrase "SSID_NAME" "Wi-Fi_PASSWORD" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
```

**3. Start wpa_supplicant**

```bash
ip link set wlan0 up
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
```

**4. Obtain an IP address through DHCP**

```bash
dhclient wlan0
# If dhclient is not installed, use udhcpc or NetworkManager to obtain an address according to the actual system environment
```

**5. Check connection status with wpa_cli**

```bash
wpa_cli -i wlan0 status
wpa_cli -i wlan0 scan
wpa_cli -i wlan0 scan_results
```

When `wpa_state=COMPLETED` and `ip_address` contains a valid address, Wi-Fi authentication and IP acquisition are basically working.

**6. Connect interactively with wpa_cli (optional)**

```bash
wpa_cli -i wlan0
> scan
> scan_results
> add_network
> set_network 0 ssid "\"SSID_NAME\""
> set_network 0 psk "\"Wi-Fi_PASSWORD\""
> enable_network 0
> save_config
> status
```

# Bluetooth Usage

The **Quectel Pi** Debian development board has built-in Bluetooth support. In the current board environment, the `bluetooth` service is active and `bluetoothctl show` can identify the controller, which indicates that the basic Bluetooth service has started.

## Method 1: Connect to a Bluetooth Device from the Debian Desktop

1. After entering the Debian desktop, open Settings.

2. Go to the Bluetooth page.

3. Turn on Bluetooth and set the target Bluetooth device to pairing/discoverable mode.

4. Select the target device from the device list, such as a Bluetooth headset, keyboard, or mouse.

5. Follow the on-screen prompts to complete Pair and Connect.

## Method 2: Connect to a Bluetooth Device with bluetoothctl

If no graphical interface is available, or if debugging is required through ADB or serial console, use `bluetoothctl`.

```bash
systemctl status bluetooth
bluetoothctl
```

After entering `bluetoothctl`, run:

```
power on
agent on
default-agent
scan on
```

Wait until the target device is found, record the device MAC address, and then run:

```
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit
```

After the device is connected, use the following commands to check the controller and device status:

```bash
bluetoothctl show
bluetoothctl devices
bluetoothctl info XX:XX:XX:XX:XX:XX
```

# Common Troubleshooting

| **Symptom** | **Troubleshooting Method** |
| --- | --- |
| Wi-Fi networks cannot be scanned | Check whether the antenna is connected. Run `rfkill list` to check whether Wi-Fi is blocked by software or hardware. Run `nmcli radio wifi on` and scan again. |
| `wlan0` does not exist | Run `ip link` and `dmesg \| grep -i wlan` to check whether the driver and firmware are loaded. |
| nmcli connection fails | Check whether the SSID and password are correct. Use `journalctl -u NetworkManager -b` to view NetworkManager logs. |
| wpa_cli shows that it cannot connect | Make sure wpa_supplicant has started, and that the control interface matches the interface used by `wpa_cli -i wlan0`. |
| Bluetooth cannot scan devices | Make sure `systemctl status bluetooth` is normal, run `bluetoothctl power on`, and confirm that the peripheral device is in discoverable mode. |

# Board-Side Confirmation Commands

When maintaining or locating issues, collect the following information first to confirm the system, interface, and service status:

```bash
cat /etc/os-release
uname -a
ip link show wlan0
nmcli general status
nmcli device status
systemctl is-active NetworkManager
systemctl is-active bluetooth
bluetoothctl show
```